<!doctype html>
<html lang="en">
<head>
	<meta charset="UTF-8">
	<meta name="viewport" content="width=device-width, initial-scale=1.0">
	<link rel="stylesheet" href="./../assets/css/combined.css">
	<link rel="shortcut icon" href="./../favicon.ico" />
	<script src="http://www.google.com/jsapi" type="text/javascript"></script>
	<script type="text/javascript">
		var path = './../';
		var class_prefix = "Fieldset::";
	</script>
	<script src="./../assets/js/combined.js"></script>
	<title>Fieldset - Classes - FuelPHP Documentation</title>
</head>
<body>
	<div id="container">
		<header id="header">
			<div class="table">
				<h1>
					<strong>FuelPHP, a PHP 5.3 Framework</strong>
					Documentation
				</h1>

				<form id="google_search">
					<p>
						<span id="search_clear">&nbsp;</span>
						<input type="submit" name="search_submit" id="search_submit" value="search" />
						<input type="text" value="" id="search_input" name="search_input" />
					</p>
				</form>
			</div>
			<nav>

				<div class="clear"></div>
			</nav>
			<a href="#" id="toc_handle">table of contents</a>
			<div class="clear"></div>
		</header>

		<div id="cse">
			<div id="cse_point"></div>
			<div id="cse_content"></div>
		</div>

		<div id="main">

			<h2>Fieldset Class</h2>

			<p>
				The Fieldset class is used to create a form and handle its validation in an object oriented way. It uses the Form
				and Validation classes. This class itself is only meant to model the fieldset and its fields while the other
				two classes do the real work.
			</p>
			<p>
				The resulting form markup is generated when passing the Fieldset instance to a View or by calling <kbd>build()</kbd>.
			</p>

			<article>
				<h4 class="method" id="method_forge">forge($name = 'default', $config = array())</h4>
				<p>The <strong>forge</strong> method returns a new Fieldset instance. Note: there can only be one instance per <kbd>$name</kbd>.</p>
				<table class="method">
					<tbody>
					<tr>
						<th class="legend">Static</th>
						<td>Yes</td>
					</tr>
					<tr>
						<th>Parameters</th>
						<td>
							<table class="parameters">
								<tbody>
									<tr>
										<th>Param</th>
										<th>Default</th>
										<th class="description">Description</th>
									</tr>
									<tr>
										<th><kbd>$name</kbd></th>
										<td><pre class="php"><code>'default'</code></pre></td>
										<td>Identifier for this fieldset</td>
									</tr>
									<tr>
										<th><kbd>$config</kbd></th>
										<td><code>array()</code></td>
										<td>Configuration array</td>
									</tr>
								</tbody>
							</table>
						</td>
					</tr>
					<tr>
						<th>Returns</th>
						<td>\Fieldset Object</td>
					</tr>
					<tr>
						<th>Example</th>
						<td>
							<pre class="php"><code>$article_form = Fieldset::forge('article');</code></pre>
						</td>
					</tr>
					</tbody>
				</table>
			</article>

			<article>
				<h4 class="method" id="method_instance">instance($instance = null)</h4>
				<p>Returns a specific instance, or the default instance (is created if necessary).</p>
				<table class="method">
					<tbody>
					<tr>
						<th class="legend">Static</th>
						<td>Yes</td>
					</tr>
					<tr>
						<th>Parameters</th>
						<td>
							<table class="parameters">
								<tbody>
									<tr>
										<th>Param</th>
										<th>Default</th>
										<th class="description">Description</th>
									</tr>
									<tr>
										<th><kbd>$instance</kbd></th>
										<td><pre class="php"><code>null</code></pre></td>
										<td>Identifier of the fieldset instance you want to retrieve</td>
									</tr>
								</tbody>
							</table>
						</td>
					</tr>
					<tr>
						<th>Returns</th>
						<td>\Fieldset Object<br />
						or <kbd>false</kbd> if the specified instance doesn't exist.</td>
					</tr>
					<tr>
						<th>Example</th>
						<td>
							<pre class="php"><code>$article_form = Fieldset::instance('article');</code></pre>
						</td>
					</tr>
					</tbody>
				</table>
			</article>

			<article>
				<h4 class="method" id="method_validation">validation()</h4>
				<p>Gets the Validation instance for the current Fieldset. Creates the Validation instance if it doesn't already exist.</p>
				<table class="method">
					<tbody>
						<tr>
							<th class="legend">Static</th>
							<td>No</td>
						</tr>
						<tr>
							<th>Returns</th>
							<td>\Validation Object</td>
						</tr>
						<tr>
							<th>Example</th>
							<td>
								<pre class="php"><code>$validation = $article_form->validation();</code></pre>
							</td>
						</tr>
					</tbody>
				</table>
			</article>

			<article>
				<h4 class="method" id="method_form">form()</h4>
				<p>Gets the Form instance for the current Fieldset. Creates the Form instance if it doesn't already exist.</p>
				<table class="method">
					<tbody>
						<tr>
							<th class="legend">Static</th>
							<td>No</td>
						</tr>
						<tr>
							<th>Returns</th>
							<td>\Form Object</td>
						</tr>
						<tr>
							<th>Example</th>
							<td>
								<pre class="php"><code>$form = $article_form->form();</code></pre>
							</td>
						</tr>
					</tbody>
				</table>
			</article>

			<article>
				<h4 class="method" id="method_add">add($name, $label = '', array $attributes = array(), array $rules = array())</h4>
				<p>Creates a Fieldset_Field instance and adds it to the current Fieldset.</p>
				<table class="method">
					<tbody>
					<tr>
						<th class="legend">Static</th>
						<td>No</td>
					</tr>
					<tr>
						<th>Parameters</th>
						<td>
							<table class="parameters">
								<tbody>
									<tr>
										<th>Param</th>
										<th>Default</th>
										<th class="description">Description</th>
									</tr>
									<tr>
										<th><kbd>$name</kbd></th>
										<td><i>required</i></td>
										<td>HTML name attribute, also used for referencing the field within the Fieldset</td>
									</tr>
									<tr>
										<th><kbd>$label</kbd></th>
										<td><pre class="php"><code>''</code></pre></td>
										<td>Field label</td>
									</tr>
									<tr>
										<th><kbd>$attributes</kbd></th>
										<td><pre class="php"><code>array()</code></pre></td>
										<td>HTML attributes as an associative array</td>
									</tr>
									<tr>
										<th><kbd>$rules</kbd></th>
										<td><pre class="php"><code>array()</code></pre></td>
										<td>Validation rules to be applied to this Field</td>
									</tr>
								</tbody>
							</table>
						</td>
					</tr>
					<tr>
						<th>Returns</th>
						<td>\Fieldset_Field Object</td>
					</tr>
					<tr>
						<th>Example</th>
						<td>
							<pre class="php"><code>$title_field = $article_form->add('article_title', 'Title', array('class' => 'pretty_input'));

// Example Radio
$ops = array('male', 'female');
$form->add(
	'gender', '',
	array('options' => $ops, 'type' => 'radio', 'value' => 'true')
);

// Example Checkbox
$ops = array('male', 'female');
$form->add(
	'gender', '',
	array('options' => $ops, 'type' => 'checkbox', 'value' => 'true')
);

// Example of an Email input, with validation rules
$form->add(
	'email', 'E-mail',
	array('type' => 'email', 'class' => 'pretty_input'),
	array('required', 'valid_email')
);

// Example of an text input, with array notation for the validation rules
$form->add(
	'name', 'Full name',
	array('type' => 'name', 'class' => 'pretty_input'),
	array(array('required'), array('valid_string', array('alpha-numeric', 'dots', 'spaces')))
);</code></pre>
						</td>
					</tr>
					</tbody>
				</table>
			</article>

			<article>
				<h4 class="method" id="method_add_before">add_before($name, $label = '', array $attributes = array(), array $rules = array(), $fieldname = null)</h4>
				<p>Creates a Fieldset_Field instance and adds it to the current Fieldset, just before an already defined field identified by <strong>$fieldname</strong>.</p>
				<table class="method">
					<tbody>
					<tr>
						<th class="legend">Static</th>
						<td>No</td>
					</tr>
					<tr>
						<th>Parameters</th>
						<td>
							<table class="parameters">
								<tbody>
									<tr>
										<th>Param</th>
										<th>Default</th>
										<th class="description">Description</th>
									</tr>
									<tr>
										<th><kbd>$name</kbd></th>
										<td><i>required</i></td>
										<td>HTML name attribute, also used for referencing the field within the Fieldset</td>
									</tr>
									<tr>
										<th><kbd>$label</kbd></th>
										<td><pre class="php"><code>''</code></pre></td>
										<td>Field label</td>
									</tr>
									<tr>
										<th><kbd>$attributes</kbd></th>
										<td><pre class="php"><code>array()</code></pre></td>
										<td>HTML attributes as an associative array</td>
									</tr>
									<tr>
										<th><kbd>$rules</kbd></th>
										<td><pre class="php"><code>array()</code></pre></td>
										<td>Validation rules to be applied to this Field</td>
									</tr>
									<tr>
										<th><kbd>$fieldname</kbd></th>
										<td><pre class="php"><code>null</code></pre></td>
										<td>Already defined field to which this field must be prepended</td>
									</tr>
								</tbody>
							</table>
						</td>
					</tr>
					<tr>
						<th>Returns</th>
						<td>\Fieldset_Field Object</td>
					</tr>
					<tr>
						<th>Example</th>
						<td>
							<pre class="php"><code>// Radio button field, to be added before the 'location' field.
$ops = array('male', 'female');
$form->add_before('gender', '', array('options' => $ops, 'type' => 'radio', 'value' => 'true'), array(), 'location');</code></pre>
						</td>
					</tr>
					</tbody>
				</table>
			</article>

			<article>
				<h4 class="method" id="method_add_after">add_after($name, $label = '', array $attributes = array(), array $rules = array(), $fieldname = null)</h4>
				<p>Creates a Fieldset_Field instance and adds it to the current Fieldset, just after an already defined field identified by <strong>$fieldname</strong>.</p>
				<table class="method">
					<tbody>
					<tr>
						<th class="legend">Static</th>
						<td>No</td>
					</tr>
					<tr>
						<th>Parameters</th>
						<td>
							<table class="parameters">
								<tbody>
									<tr>
										<th>Param</th>
										<th>Default</th>
										<th class="description">Description</th>
									</tr>
									<tr>
										<th><kbd>$name</kbd></th>
										<td><i>required</i></td>
										<td>HTML name attribute, also used for referencing the field within the Fieldset</td>
									</tr>
									<tr>
										<th><kbd>$label</kbd></th>
										<td><pre class="php"><code>''</code></pre></td>
										<td>Field label</td>
									</tr>
									<tr>
										<th><kbd>$attributes</kbd></th>
										<td><pre class="php"><code>array()</code></pre></td>
										<td>HTML attributes as an associative array</td>
									</tr>
									<tr>
										<th><kbd>$rules</kbd></th>
										<td><pre class="php"><code>array()</code></pre></td>
										<td>Validation rules to be applied to this Field</td>
									</tr>
									<tr>
										<th><kbd>$fieldname</kbd></th>
										<td><pre class="php"><code>null</code></pre></td>
										<td>Already defined field to which this field must be appended</td>
									</tr>
								</tbody>
							</table>
						</td>
					</tr>
					<tr>
						<th>Returns</th>
						<td>\Fieldset_Field Object</td>
					</tr>
					<tr>
						<th>Example</th>
						<td>
							<pre class="php"><code>// Radio button field, to be added after the 'location' field.
$ops = array('male', 'female');
$form->add_after('gender', '', array('options' => $ops, 'type' => 'radio', 'value' => 'true'), array(), 'location');</code></pre>
						</td>
					</tr>
					</tbody>
				</table>
			</article>

			<article>
				<h4 class="method" id="method_field">field($name = null)</h4>
				<p>Gets one or all Fieldset_Field instances for the current Fieldset.</p>
				<table class="method">
					<tbody>
					<tr>
						<th class="legend">Static</th>
						<td>No</td>
					</tr>
					<tr>
						<th>Parameters</th>
						<td>
							<table class="parameters">
								<tbody>
									<tr>
										<th>Param</th>
										<th>Default</th>
										<th class="description">Description</th>
									</tr>
									<tr>
										<th><kbd>$name</kbd></th>
										<td><pre class="php"><code>null</code></pre></td>
										<td>The name of an existing field in this Fieldset or null to get all fields.</td>
									</tr>
								</tbody>
							</table>
						</td>
					</tr>
					<tr>
						<th>Returns</th>
						<td>\Fieldset_Field Object<br />
						or <kbd>array()</kbd> of Fieldset_Fields</td>
					</tr>
					<tr>
						<th>Example</th>
						<td>
							<pre class="php"><code>$fields = $article_form->field();
$title_field = $article_form->field('article_title');</code></pre>
						</td>
					</tr>
					</tbody>
				</table>
			</article>

			<article>
				<h4 class="method" id="method_add_model">add_model($class, $instance = null, $method = 'set_form_fields')</h4>
				<p>Add a model's fields. The model must have a method <kbd>set_form_fields()</kbd> that takes this Fieldset instance and adds fields to it.<br />
					<kbd>Orm\Model</kbd> have support this build in.</p>
				<table class="method">
					<tbody>
					<tr>
						<th class="legend">Static</th>
						<td>No</td>
					</tr>
					<tr>
						<th>Parameters</th>
						<td>
							<table class="parameters">
								<tbody>
									<tr>
										<th>Param</th>
										<th>Default</th>
										<th class="description">Description</th>
									</tr>
									<tr>
										<th><kbd>$class</kbd></th>
										<td><i>required</i></td>
										<td>Either a full classname (including full namespace) or object instance of the model to get fields from.</td>
									</tr>
									<tr>
										<th><kbd>$instance</kbd></th>
										<td><pre class="php"><code>null</code></pre></td>
										<td>Array or object that has the exactly same named properties to populate the fields. (Takes the field names from the model and fetches the remaining parameters from this array/object.</td>
									</tr>
									<tr>
										<th><kbd>$method</kbd></th>
										<td><pre class="php"><code>'set_form_fields'</code></pre></td>
										<td>The name of the method name to call on the model for field fetching.</td>
									</tr>
								</tbody>
							</table>
						</td>
					</tr>
					<tr>
						<th>Returns</th>
						<td>\Fieldset Object</td>
					</tr>
					<tr>
						<th>Example</th>
						<td>
							<pre class="php"><code>$article_form = Fieldset::forge('article');
$article_form->add_model('Model_Article');</code></pre>
						</td>
					</tr>
					</tbody>
				</table>
			</article>

			<article>
				<h4 class="method" id="method_set_config">set_config($config, $value = null)</h4>
				<p>Sets a config value on the fieldset.</p>
				<table class="method">
					<tbody>
					<tr>
						<th class="legend">Static</th>
						<td>No</td>
					</tr>
					<tr>
						<th>Parameters</th>
						<td>
							<table class="parameters">
								<tbody>
									<tr>
										<th>Param</th>
										<th>Default</th>
										<th class="description">Description</th>
									</tr>
									<tr>
										<th><kbd>$config</kbd></th>
										<td><em>required</em></td>
										<td>Configuration array.</td>
									</tr>
									<tr>
										<th><kbd>$value</kbd></th>
										<td><pre class="php"><code>null</code></pre></td>
										<td>If specified, sets the item to set from the passed Configuration array.</td>
									</tr>
								</tbody>
							</table>
						</td>
					</tr>
					<tr>
						<th>Returns</th>
						<td>\Fieldset Object</td>
					</tr>
					<tr>
						<th>Example</th>
						<td>
							<pre class="php"><code>$article_form->set_config($config);

// or

$article_form->set_config('key', 'value');</code></pre>
						</td>
					</tr>
					</tbody>
				</table>
			</article>

			<article id="method_get_config">
				<h4 class="method" id="method_get_config">get_config($key = null, $default = null)</h4>
				<p>Get the configuration array or one or more config values by key.</p>
				<table class="method">
					<tbody>
					<tr>
						<th class="legend">Static</th>
						<td>No</td>
					</tr>
					<tr>
						<th>Parameters</th>
						<td>
							<table class="parameters">
								<tbody>
									<tr>
										<th>Param</th>
										<th>Default</th>
										<th class="description">Description</th>
									</tr>
									<tr>
										<th><kbd>$key</kbd></th>
										<td><pre class="php"><code>null</code></pre></td>
										<td>A single key or multiple in an array, empty to fetch all.</td>
									</tr>
									<tr>
										<th><kbd>$default</kbd></th>
										<td><pre class="php"><code>null</code></pre></td>
										<td>A single config value or multiple in an array if $key input is an array to be returned if the items aren't found.</td>
									</tr>
								</tbody>
							</table>
						</td>
					</tr>
					<tr>
						<th>Returns</th>
						<td>array() or mixed</td>
					</tr>
					<tr>
						<th>Example</th>
						<td>
							<pre class="php"><code>$config = $article_form->get_config();</code></pre>
						</td>
					</tr>
					</tbody>
				</table>
			</article>

			<article id="method_get_name">
				<h4 class="method" id="method_get_name">get_name()</h4>
				<p>Get the identifier of the fieldset instance.</p>
				<table class="method">
					<tbody>
					<tr>
						<th class="legend">Static</th>
						<td>No</td>
					</tr>
					<tr>
						<th>Parameters</th>
						<td>(none)</td>
					</tr>
					<tr>
						<th>Returns</th>
						<td>string</td>
					</tr>
					<tr>
						<th>Example</th>
						<td>
                            <pre class="php"><code>$article_form = Fieldset::forge('article');
$name = $article_form->get_name();  // 'article'</code></pre>
						</td>
					</tr>
					</tbody>
				</table>
			</article>

			<article>
				<h4 class="method" id="method_populate">populate($input, $repopulate = false)</h4>
				<p>Set initial field values to the given input, optionally set it to repopulate after that as well.</p>
				<table class="method">
					<tbody>
					<tr>
						<th class="legend">Static</th>
						<td>No</td>
					</tr>
					<tr>
						<th>Parameters</th>
						<td>
							<table class="parameters">
								<tbody>
									<tr>
										<th>Param</th>
										<th>Default</th>
										<th class="description">Description</th>
									</tr>
									<tr>
										<th><kbd>$input</kbd></th>
										<td><i>required</i></td>
										<td>An object or associative array of values to assign to their respective Fields,
											or a Model instance to take the values from.</td>
									</tr>
									<tr>
										<th><kbd>$repopulate</kbd></th>
										<td><code>false</code></td>
										<td>Use the repopulate() method after initial populating</td>
									</tr>
								</tbody>
							</table>
						</td>
					</tr>
					<tr>
						<th>Returns</th>
						<td>\Fieldset Object</td>
					</tr>
					<tr>
						<th>Example</th>
						<td>
							<pre class="php"><code>$article_form->populate($model);</code></pre>
						</td>
					</tr>
					</tbody>
				</table>
			</article>

			<article>
				<h4 class="method" id="method_repopulate">repopulate()</h4>
				<p>Set all field values to the input send by a form submission (uses the form <kbd>method</kbd> attribute
					to decide wether to check POST or GET).</p>
				<table class="method">
					<tbody>
					<tr>
						<th class="legend">Static</th>
						<td>No</td>
					</tr>
					<tr>
						<th>Parameters</th>
						<td>
							<i>None</i>
						</td>
					</tr>
					<tr>
						<th>Returns</th>
						<td>\Fieldset Object</td>
					</tr>
					<tr>
						<th>Example</th>
						<td>
							<pre class="php"><code>$article_form->repopulate();</code></pre>
						</td>
					</tr>
					</tbody>
				</table>
			</article>

			<article>
				<h4 class="method" id="method_build">build($action = null)</h4>
				<p>Alias for $this->form()->build() for this fieldset. Generates the HTML form markup. See <a href="form.html">Form</a>.</p>
				<table class="method">
					<tbody>
					<tr>
						<th class="legend">Static</th>
						<td>No</td>
					</tr>
					<tr>
						<th>Parameters</th>
						<td>
							<table class="parameters">
								<tbody>
									<tr>
										<th>Param</th>
										<th>Default</th>
										<th class="description">Description</th>
									</tr>
									<tr>
										<th><kbd>$action</kbd></th>
										<td><pre class="php"><code>null</code></pre></td>
										<td>A URL for the <kbd>action</kbd> attribute of the form.</td>
									</tr>
								</tbody>
							</table>
						</td>
					</tr>
					<tr>
						<th>Returns</th>
						<td>string HTML markup</td>
					</tr>
					<tr>
						<th>Example</th>
						<td>
							<pre class="php"><code>$this->template->form = $article_form->build(Uri::create('article/submit'));</code></pre>
						</td>
					</tr>
					</tbody>
				</table>
			</article>

			<article>
				<h4 class="method" id="method_disable">disable($field)</h4>
				<p>
					The <kbd>disable</kbd> method allows you to disable a field from being build. You can use this if you want to alter the sequence of fields
					on the form, or to create more complex layouts without having to build individual fields.
				</p>
				<table class="method">
					<tbody>
					<tr>
						<th class="legend">Static</th>
						<td>No</td>
					</tr>
					<tr>
						<th>Parameters</th>
						<td>
							<table class="parameters">
								<tbody>
									<tr>
										<th>Param</th>
										<th>Default</th>
										<th class="description">Description</th>
									</tr>
									<tr>
										<th><kbd>$field</kbd></th>
										<td>required</td>
										<td>The specific field you want to disable.</td>
									</tr>
								</tbody>
							</table>
						</td>
					</tr>
					<tr>
						<th>Returns</th>
						<td>\Fieldset Object</td>
					</tr>
					<tr>
						<th>Throws</th>
						<td>RuntimeException, if the field given is not defined</td>
					</tr>
					<tr>
						<th>Example</th>
						<td>
							<pre class="php"><code>$fieldset->disable('name');</code></pre>
						</td>
					</tr>
					</tbody>
				</table>
				<p class="note">The field is not removed from the fieldset, so it will still be validated.</p>
			</article>

			<article>
				<h4 class="method" id="method_enable">enable($field)</h4>
				<p>The <kbd>enable</kbd> method allows you to re-enable a field that has been <kbd>disable</kbd>d before.</p>
				<table class="method">
					<tbody>
					<tr>
						<th class="legend">Static</th>
						<td>No</td>
					</tr>
					<tr>
						<th>Parameters</th>
						<td>
							<table class="parameters">
								<tbody>
									<tr>
										<th>Param</th>
										<th>Default</th>
										<th class="description">Description</th>
									</tr>
									<tr>
										<th><kbd>$field</kbd></th>
										<td>required</td>
										<td>The specific field you want to enable.</td>
									</tr>
								</tbody>
							</table>
						</td>
					</tr>
					<tr>
						<th>Returns</th>
						<td>\Fieldset Object</td>
					</tr>
					<tr>
						<th>Throws</th>
						<td>RuntimeException, if the field given is not defined</td>
					</tr>
					<tr>
						<th>Example</th>
						<td>
							<pre class="php"><code>$fieldset->enable('name');</code></pre>
						</td>
					</tr>
					</tbody>
				</table>
			</article>

			<article>
				<h4 class="method" id="method_input">input($field = null)</h4>
				<p>Alias for $this->validation()->input(). Gets an array of validated input value(s) from either POST data or given input. See <a href="validation/validation.html#usage">Validation</a>.</p>
				<table class="method">
					<tbody>
					<tr>
						<th class="legend">Static</th>
						<td>No</td>
					</tr>
					<tr>
						<th>Parameters</th>
						<td>
							<table class="parameters">
								<tbody>
									<tr>
										<th>Param</th>
										<th>Default</th>
										<th class="description">Description</th>
									</tr>
									<tr>
										<th><kbd>$field</kbd></th>
										<td><pre class="php"><code>null</code></pre></td>
										<td>A specific field for which to get the input.</td>
									</tr>
								</tbody>
							</table>
						</td>
					</tr>
					<tr>
						<th>Returns</th>
						<td>Array of input or string value of specified field</td>
					</tr>
					<tr>
						<th>Example</th>
						<td>
							<pre class="php"><code>$input_values = $article_form->input();</code></pre>
						</td>
					</tr>
					</tbody>
				</table>
			</article>

			<article>
				<h4 class="method" id="method_validated">validated($field = null)</h4>
				<p>Alias for $this->validation()->validated(). Gets an array of input value(s) that passed validation. See <a href="validation/validation.html#usage">Validation</a>.</p>
				<table class="method">
					<tbody>
					<tr>
						<th class="legend">Static</th>
						<td>No</td>
					</tr>
					<tr>
						<th>Parameters</th>
						<td>
							<table class="parameters">
								<tbody>
									<tr>
										<th>Param</th>
										<th>Default</th>
										<th class="description">Description</th>
									</tr>
									<tr>
										<th><kbd>$field</kbd></th>
										<td><pre class="php"><code>null</code></pre></td>
										<td>A specific field for which to get the input.</td>
									</tr>
								</tbody>
							</table>
						</td>
					</tr>
					<tr>
						<th>Returns</th>
						<td>Array of input or string value of specified field, or <kbd>false</kbd> if the field isn't found</td>
					</tr>
					<tr>
						<th>Example</th>
						<td>
							<pre class="php"><code>$validated_values = $article_form->validated();</code></pre>
						</td>
					</tr>
					</tbody>
				</table>
			</article>

			<article>
				<h4 class="method" id="method_error">error($field = null)</h4>
				<p>Alias for $this->validation()->error(). Gets an array of input value(s) that did not pass validation. See <a href="validation/validation.html#usage">Validation</a>.</p>
				<table class="method">
					<tbody>
					<tr>
						<th class="legend">Static</th>
						<td>No</td>
					</tr>
					<tr>
						<th>Parameters</th>
						<td>
							<table class="parameters">
								<tbody>
									<tr>
										<th>Param</th>
										<th>Default</th>
										<th class="description">Description</th>
									</tr>
									<tr>
										<th><kbd>$field</kbd></th>
										<td><pre class="php"><code>null</code></pre></td>
										<td>A specific field for which to get the input.</td>
									</tr>
								</tbody>
							</table>
						</td>
					</tr>
					<tr>
						<th>Returns</th>
						<td>Array of input or string value of specified field, or <kbd>false</kbd> if the field isn't found</td>
					</tr>
					<tr>
						<th>Example</th>
						<td>
							<pre class="php"><code>$errors = $article_form->error();</code></pre>
						</td>
					</tr>
					</tbody>
				</table>
			</article>

			<article>
				<h4 class="method" id="method_show_errors">show_errors(Array $config = array())</h4>
				<p>Alias for $this->validation()->show_errors(). Returns all errors in a list or with set markup from the $config parameter. See <a href="validation/validation.html#usage">Validation</a>.</p>
				<table class="method">
					<tbody>
					<tr>
						<th class="legend">Static</th>
						<td>No</td>
					</tr>
					<tr>
						<th>Parameters</th>
						<td>
							<table class="parameters">
								<tbody>
									<tr>
										<th>Param</th>
										<th>Default</th>
										<th class="description">Description</th>
									</tr>
									<tr>
										<th><kbd>$config</kbd></th>
										<td><pre class="php"><code>array()</code></pre></td>
										<td>Uses keys open_list, close_list, open_error, close_error &amp; no_errors. Overrides the values </td>
									</tr>
								</tbody>
							</table>
						</td>
					</tr>
					<tr>
						<th>Returns</th>
						<td>Array of input or string value of specified field, or <kbd>false</kbd> if the field isn't found</td>
					</tr>
					<tr>
						<th>Example</th>
						<td>
							<pre class="php"><code>$all_errors = $article_form->show_errors();</code></pre>
						</td>
					</tr>
					</tbody>
				</table>
			</article>

			<article>
				<h4 class="method" id="method_set_tabular_form">set_tabular_form($model, $relation, $parent, $blanks = 1)</h4>
				<p>Define an embedded fieldset on a related ORM model to create a One-to-Many form.</p>
				<table class="method">
					<tbody>
					<tr>
						<th class="legend">Static</th>
						<td>No</td>
					</tr>
					<tr>
						<th>Parameters</th>
						<td>
							<table class="parameters">
								<tbody>
									<tr>
										<th>Param</th>
										<th>Default</th>
										<th class="description">Description</th>
									</tr>
									<tr>
										<th><kbd>$model</kbd></th>
										<td><i>required</i></td>
										<td>Fully namespaced name of the related model on which the form must be generated</td>
									</tr>
									<tr>
										<th><kbd>$relation</kbd></th>
										<td><i>required</i></td>
										<td>Name of the relation of the parent object that relates to $model</td>
									</tr>
									<tr>
										<th><kbd>$parent</kbd></th>
										<td><i>required</i></td>
										<td>Parent object that is used to generate the main form, and contains the related records to be displayed in the tabular form</td>
									</tr>
									<tr>
										<th><kbd>$blanks</kbd></th>
										<td><pre class="php"><code>1</code></pre></td>
										<td>Number of empty rows to be displayed in the tabular form</td>
									</tr>
								</tbody>
							</table>
						</td>
					</tr>
					<tr>
						<th>Returns</th>
						<td>Fieldset, for chaining</td>
					</tr>
					<tr>
						<th>Throws</th>
						<td>RuntimeException, if incorrect parameters are passed</td>
					</tr>
					<tr>
						<th>Example</th>
						<td>
							See <a href="#one_to_many_forms">below</a>...
						</td>
					</tr>
					</tbody>
				</table>
				<p class="note">
					The tabular form is displayed in a table, controlled by template definitions in the <kbd>config/form.php</kbd>
					configuration file. You are free to modify these templates, but you should leave the table structure, as the
					fieldset class will add the table headers based on the fields present in each row. This will generate invalid HTML
					if you remove the table and row definition from the template.
				</p>
			</article>

			<article>
				<h4 class="method" id="method_get_tabular_form">get_tabular_form()</h4>
				<p>Return the name of the defined tabular form.</p>
				<table class="method">
					<tbody>
					<tr>
						<th class="legend">Static</th>
						<td>No</td>
					</tr>
					<tr>
						<th>Parameters</th>
						<td>
							None
						</td>
					</tr>
					<tr>
						<th>Returns</th>
						<td>mixed, the name of the form, or <kbd>false</kbd> if the fieldset is not a tabular form</td>
					</tr>
					<tr>
						<th>Example</th>
						<td>
							<pre class="php"><code>if ($name = $form->get_tabular_form())
{
	echo '$form is a tabular fieldset named', $name;
}</code></pre>
						</td>
					</tr>
					</tbody>
				</table>
			</article>

			<article>
				<h2 id="create_forms_orm">Creating Forms with ORM Models</h2>

				<p>The Fieldset class can be used to create forms from ORM models. The following example will build a
					form based on the fields specified in <kbd>$_properties</kbd> of your model. In the example, $article
					is an instance of Model_Article.</p>

				<pre class="php"><code>echo Fieldset::forge('article')->add_model($article)->populate($article, true)->build();</code></pre>

				<p>If you do not wish every property of the model to be on your form, you can set the form type of
					those to <code>false</code> and they will not be generated.<br />
					This actually uses the <a href="../packages/orm/observers/included.html#os_validation">
					Observer_Validation</a> behind the scenes, but you do not need to add it as an observer for this to
					work.</p>
			</article>

			<article>
			<h2 id="one_to_many_forms">Creating One-to-Many forms with ORM Models</h2>
				<p>The Fieldset class can also be used to create forms for an ORM model object and a Many relation. This is done by embedding
					a tabular form fieldset into the main form fieldset, specifying the related model and the name of the relation.</p>

				<p>By default, the One-to-Many fieldset is displayed in tabular form, controlled by the template in the <kbd>config/form.php</kbd> file.
				</p>

				<pre class='php'><code>// We're going to create a one-to-many form of an article, identified by $id, and it's comments

// get the article and it's related comments
$article = Model_Article::find($id, array('related' => array('comments')));

// create the form fieldset for this article using the ORM model's form definition
$form = Fieldset::forge('article')->add_model($article);

/*
 * add the tabular form to it to create the one-to-many table.
 *
 * the data is provided by the relation 'comments' of the $article object, which
 * are objects of the class 'Model_Comments'.
 *
 * you can disable the fieldset tag to avoid embedded fieldsets in your form
 */
$form->add(\Fieldset::forge('tabular')->set_tabular_form('Model_Comments', 'comments', $article)->set_fieldset_tag(false));
				</code></pre>

				<p class="note">This only works for related models that <strong>DO NOT</strong> have a compound key!</p>

				<p>
					A tabular form generates HTML input tags that use an array with the name of the relation specified, and the primary key value of the
					record as it's index value. Any blank rows that are added at the bottom of the table will use the relation name, with a '_new' suffix.
					This will allow you to update the parent record, and all related records, in one go, and process the new lines separately.
				</p>
				<p>
					In this example, you'll see input tag names like <code>comments[12][fieldA]</code> for existing rows (in this case a row with <code>id = 12</code>,
					and <code>comments_new[0][fieldA]</code> for a field in the first blank line.
				</p>
				<pre class='php'><code>// Process the posted one-to-many form
if (\Input::post())
{
	// validate the input
	$form->validation()->run();

	// if validated, save the updates
	if ( ! $form->validation()->error())
	{
		// update the article record, and any comment record changes
		$article->from_array($data);

		// do we need to delete tabular form records?
		foreach ($data['comments'] as $id => $row)
		{
			if ($id and ! empty($row['_delete']))
			{
				unset($article->comments[$id]);
			}
		}

		// do we have a new tabular form record data (assuming we've added only one blank line)?
		$data = array_filter($data['comments_new'][0]);

		$new_errors = false;
		if ( ! empty($data))
		{
			// check for required fields
			if (empty($data['fieldA']) or empty($data['fieldB']))
			{
				$new_errors = true;
				// display an error message about missing required fields here...
			}
			else
			{
				// create a new related record
				$article->comments[] = Model_Comments::forge(array('article_id' => $article->id, 'fieldA' => $data['fieldA'], 'fieldB' => $data['fieldB']));
			}
		}

		// save the updates
		if ( ! $new_errors)
		{
			if ($article->save())
			{
				// display a save-succesful message here and redirect away
			}
			else
			{
				// display an error message, save was not succesful
			}
		}
	}
	else
	{
		// inform the user validation failed
	}
}</code></pre>
			</article>

			<article>
			<h2 id="form_attributes">Form Attributes</h2>
			<p>The layout of the forms generated by the fieldset is controlled by the <strong>form.php</strong> configuration file.</p>

				<p>
					The following configuration values can be defined:
				</p>

				<table class="config">
					<tbody>
						<tr class="header">
							<th>Param</th>
							<th>Type</th>
							<th>Default</th>
							<th>Description</th>
						</tr>
						<tr>
							<th>prep_value</th>
							<td>boolean</td>
							<td><pre class="php"><code>true</code></pre></td>
							<td>
								If true, form values passed to the fieldset will be escaped using <kbd>Security::htmlentities()</kbd>.
							</td>
						</tr>
						<tr>
							<th>auto_id</th>
							<td>boolean</td>
							<td><pre class="php"><code>true</code></pre></td>
							<td>
								If true, the id attribute for form fields will be generated if not assigned to the fields manually.
							</td>
						</tr>
						<tr>
							<th>auto_id_prefix</th>
							<td>string</td>
							<td><pre class="php"><code>'form_'</code></pre></td>
							<td>
								When auto_id is true, prefix the generated id attributes with this string.
							</td>
						</tr>
						<tr>
							<th>form_method</th>
							<td>string</td>
							<td><pre class="php"><code>'post'</code></pre></td>
							<td>
								Type of form action to generate. Can be 'get' or 'post'.
							</td>
						</tr>
						<tr>
							<th>form_template</th>
							<td>string</td>
							<td><pre class="php"><code>'\n\t\t{open}<br />\n\t\t&lt;table&gt;\n{fields}\n\t\t&lt;/table&gt;<br />\n\t\t{close}\n'</code></pre></td>
							<td>
								String containing the placeholders for opening- and closing the form, and for the list of input fields.
							</td>
						</tr>
						<tr>
							<th>field_template</th>
							<td>string</td>
							<td><pre class="php"><code>'\t\t&lt;tr&gt;<br />\n\t\t\t&lt;td class=\"{error_class}\"&gt;<br />{label}{required}&lt;/td&gt;<br />\n\t\t\t&lt;td class=\"{error_class}\"&gt;{field}<br />&lt;span&gt;{description}&lt;/span&gt; {error_msg}<br />&lt;/td&gt;\n\t\t&lt;/tr&gt;\n'</code></pre></td>
							<td>
								String containing the placeholders for generating a single input field.
							</td>
						</tr>
						<tr>
							<th>multi_field_template</th>
							<td>string</td>
							<td><pre class="php"><code>'\t\t&lt;tr&gt;<br />\n\t\t\t&lt;td class=\"{error_class}\"&gt;<br />{group_label}{required}&lt;/td&gt;<br />\n\t\t\t&lt;td class=\"{error_class}\"&gt;{fields}<br />\n\t\t\t\t{field} {label}<br />\n{fields}&lt;span&gt;{description}&lt;/span&gt;<br />\t\t\t{error_msg}\n\t\t\t&lt;/td&gt;\n\t\t&lt;/tr&gt;\n'</code></pre></td>
							<td>
								String containing the placeholders for generating a single input field with multiple inputs, like a group of radio buttons or checkboxes.
							</td>
						</tr>
						<tr>
							<th>error_template</th>
							<td>string</td>
							<td><pre class="php"><code>'&lt;span&gt;{error_msg}&lt;/span&gt;'</code></pre></td>
							<td>
								String containing the placeholders for generating input error messages.
							</td>
						</tr>
						<tr>
							<th>group_label</th>
							<td>string</td>
							<td><pre class="php"><code>'&lt;span&gt;{label}&lt;/span&gt;'</code></pre></td>
							<td>
								String containing the placeholders for generating a label for multi field inputs.
							</td>
						</tr>
						<tr>
							<th>required_mark</th>
							<td>string</td>
							<td><pre class="php"><code>'*'</code></pre></td>
							<td>
								String containing the HTML to mark input fields as required.
							</td>
						</tr>
						<tr>
							<th>inline_errors</th>
							<td>boolean</td>
							<td><pre class="php"><code>false</code></pre></td>
							<td>
								If true, validation error messages will be displayed inline in the form.
							</td>
						</tr>
						<tr>
							<th>error_class</th>
							<td>string</td>
							<td><pre class="php"><code>null</code></pre></td>
							<td>
								CSS class name to apply to error messages.
							</td>
						</tr>
						<tr>
							<th>label_class</th>
							<td>string</td>
							<td><pre class="php"><code>null</code></pre></td>
							<td>
								CSS class name to apply to field labels.
							</td>
						</tr>
						<tr>
							<th>tabular_form_template</th>
							<td>string</td>
							<td><pre class="php"><code>'&lt;table&gt;{fields}&lt;/table&gt;\n'</code></pre></td>
							<td>
								template for the complete tabular form with all it's rows.
							</td>
						</tr>
						<tr>
							<th>tabular_field_template</th>
							<td>string</td>
							<td><pre class="php"><code>'{field}'</code></pre></td>
							<td>
								Template for embedding a child fieldset in a tabular form.
							</td>
						</tr>
						<tr>
							<th>tabular_row_template</th>
							<td>string</td>
							<td><pre class="php"><code>'&lt;tr&gt;{fields}&lt;/tr&gt;\n'</code></pre></td>
							<td>
								Template for generating a single row in a tabular form.
							</td>
						</tr>
						<tr>
							<th>tabular_row_field_template</th>
							<td>string</td>
							<td><pre class="php"><code>'\t\t\t&lt;td&gt;{label}{required}&nbsp;{field} {error_msg}&lt;/td&gt;\n'</code></pre></td>
							<td>
								Template for generating a single field in a row of a tabular form.
							</td>
						</tr>
						<tr>
							<th>tabular_delete_label</th>
							<td>string</td>
							<td><pre class="php"><code>'Delete?'</code></pre></td>
							<td>
								Column header for the row delete checkbox.
							</td>
						</tr>
					</tbody>
				</table>

				<h3 id="form_attributes_macros">Form Attribute macro's</h3>

				<p>The following macro's can be used in a form template.</p>

				<table class="config">
					<tbody>
						<tr class="header">
							<th>Param</th>
							<th>Description</th>
						</tr>
						<tr>
							<th>{open}</th>
							<td>Form open tag, generated by Form::open();</td>
						</tr>
						<tr>
							<th>{close}</th>
							<td>Form close tag, generated by Form::open();</td>
						</tr>
						<tr>
							<th>{fields}</th>
							<td>The block of HTML containing all generated input fields.</td>
						</tr>
						<tr>
							<th>{label}</th>
							<td>Input field label, generated by Form::label();</td>
						</tr>
						<tr>
							<th>{required}</th>
							<td>String indicating the input field is required.</td>
						</tr>
						<tr>
							<th>{error_class}</th>
							<td>Configured class to be applied to error messages.</td>
						</tr>
						<tr>
							<th>{field}</th>
							<td>Generated HTML for the individual input field.</td>
						</tr>
						<tr>
							<th>{description}</th>
							<td>String the field description or a help text to be displayed.</td>
						</tr>
						<tr>
							<th>{error_msg}</th>
							<td>String containing the formatted error message as returned by validation.</td>
						</tr>
						<tr>
							<th>{group_label}</th>
							<td>Input field label for grouped input fields, generated by Form::label();</td>
						</tr>
					</tbody>
				</table>

			</article>

			<article>
			<h2 id="modify_form_attributes">Modify Form Attributes</h2>
				<p>Changing the attributes of the <kbd>form()</kbd> instance in the fieldset can be done in two ways. You can either provide your options in the <kbd>forge()</kbd> method's attributes array, or modify the form instance directly.</p>
				<pre class='php'><code>// Use the form_attributes option in the attributes of the Fieldset object
$fieldset = Fieldset::forge('article', array(
	'form_attributes' => array(
		'id' => 'edit_article_form',
		'name' => 'edit_article'
		)
	)
);

// Modify the form instance directly
$fieldset->form()->set_attribute('id', 'edit_article_form');
				</code></pre>
			</article>

			<p><strong>More examples to be written.</strong></p>

		</div>

		<footer>
			<p>
				&copy; FuelPHP Development Team 2010-2013 - <a href="http://fuelphp.com">FuelPHP</a> is released under the MIT license.
			</p>
		</footer>
	</div>
</body>
</html>
